<HTML>
<HEAD>
<TITLE></TITLE>
</HEAD>
<BODY BGCOLOR="#C0C0C0">

<A href="../home.htm">
<IMG width=343 height=58 border=0 SRC="welcom.gif" ALT="Welcome"></A>

<H2>ASxxxx Utility Programs</H2>

<A NAME = "TOP"></A> 
<IMG width=576 height=5 border=0 SRC="rnbow.gif">
<BR>
<A NAME = "Utilities"> </A>
<H3><B>
<IMG SRC = "green.gif" ALT = "-">... The ASxxxx Utilities</A>
</B></H3>
<H4><B><UL> 
<LI><A HREF= #ASXSCN>  Diagnostic Listing File Scanner</A>
<LI><A HREF= #ASXCNV>  Diagnostic Assembler File Creator</A>
<LI><A HREF= #ASCHECK>  ASxxxx Diagnostic Assembler</A>
<BR><BR>
<LI><A HREF="asxdoc.htm#TOP"> Go to the Documentation Index</A>
</UL></B></H4>

<HR SIZE=3 WIDTH=100% ALIGN=Center NOSHADE>
<H4><B><PRE>
<A NAME = "ASXSCN"></A><FONT COLOR="#FF0000">The ASXSCN Listing File Scanner</FONT>

   The  program  ASXSCN  is  a debugging utility program used to
verify ASxxxx assembler code generation.  The program may be in-
voked with any of the following options:  

        Usage: [-dqx234i] file
          d    decimal listing
          q    octal   listing
          x    hex     listing (default)
          2    16-Bit  address (default)
          3    24-Bit  address
          4    32-Bit  address
          i    ignore relocation flags


   Select  one of the -d, -q, or -x options to match the listing
file format and select only one of the -2, -3, or -4 options  to
match  the  addressing range of the listing file.  The -i option
inhibits the verification  of  the  assembler  relocation  flags
generated by the ASxxxx assemblers -f or -ff options.  

   Each  source assembly line selected for verification must in-
clude the expected output code in the comment field of the line.
The  following  has  been  extracted  from the ASF2MC8 test file
tf2mc8.asm:  

        reti            ; 30
        call  ext       ; 31s12r34
        subc  a         ; 32
        subcw a         ; 33
        subc  a,#v22    ; 34r22
        subc  a,*dir    ; 35*33
        subc  a,@ix+off ; 36r44
        subc  a,@ep     ; 37

The  r,  s,  and * are specific address relocation flags created
when the -ff option is specified with any ASxxxx assembler.  

   Invoking the assembler:  

        asf2mc8 -gloaxff tf2mc8

produces a listing file:  

033B 30          677    reti            ; 30
033C 31s12r34    678    call  ext       ; 31s12r34
033F 32          679    subc  a         ; 32
0340 33          680    subcw a         ; 33
0341 34r22       681    subc  a,#v22    ; 34r22
0343 35*33       682    subc  a,*dir    ; 35*33
0345 36r44       683    subc  a,@ix+off ; 36r44
0347 37          684    subc  a,@ep     ; 37

   The  expected code can be compared with the generated code by
invoking the scanning program:  

        asxscn tf2mc8.lst
        0 code error(s) found in file tf2mc8.lst

The assembled code can also be linked:  

        aslink -u ...options... t2fc8

to create an updated listing file:  

033B 30          677    reti            ; 30
033C 31 12 34    678    call  ext       ; 31s12r34
033F 32          679    subc  a         ; 32
0340 33          680    subcw a         ; 33
0341 34 22       681    subc  a,#v22    ; 34r22
0343 35 33       682    subc  a,*dir    ; 35*33
0345 36 44       683    subc  a,@ix+off ; 36r44

which resolves all relocations and removes the relocation flags.
This file can also be verified:  

        asxscn -i tf2mc8.rst
        0 code error(s) found in file tf2mc8.rst


   The  verification  of  both  the .lst and .rst files from the
same assembler test file requires careful definition of external
variables  so  that  the  assembler  listing file and the linker
listing file have the same code values.  

</PRE></B></H4>
<H5><A HREF= #Utilities> =&gt; Section Index</A></H5>
<HR SIZE=3 WIDTH=100% ALIGN=Center NOSHADE>
<H4><B><PRE>
<A NAME = "ASXCNV"></A><FONT COLOR="#FF0000">The ASXCNV Diagnostic Assembler File Creator</FONT>

   The  program  ASXCNV  is  a debugging utility program used to
create an assembler file with verification  data.   The  program
may be invoked with any of the following options:  

        Usage: [-dqx234] file
          d    decimal listing
          q    octal   listing
          x    hex     listing (default)
          2    16-Bit  address (default)
          3    24-Bit  address
          4    32-Bit  address


   Select  one of the -d, -q, or -x options to match the listing
file format and select only one of the -2, -3, or -4 options  to
match the addressing range of the listing file.  

   Each source assembly line which creates output data will have
the data appended to the source line as a comment.  The appended
comment will contain the relocation codes if they are present in
the listing file.  Any existing comment  on  the  line  will  be
overwritten.  

   Given an existing listing file, a.lst, containing:  

033B 30          677    reti
033C 31s12r34    678    call  ext
033F 32          679    subc  a
0340 33          680    subcw a
0341 34r22       681    subc  a,#v22
0343 35*33       682    subc  a,*dir
0345 36r44       683    subc  a,@ix+off
0347 37          684    subc  a,@ep

A  converted  listing  file  can  be created using the following
command:  

        asxcnv -d2 a.lst

The  created output file, a.out, is a new assembly file now con-
tain the verification data in the comments:  

        reti            ; 30
        call  ext       ; 31s12r34
        subc  a         ; 32
        subcw a         ; 33
        subc  a,#v22    ; 34r22
        subc  a,*dir    ; 35*33
        subc  a,@ix+off ; 36r44
        subc  a,@ep     ; 37

</PRE></B></H4>
<H5><A HREF= #Utilities> =&gt; Section Index</A></H5>
<HR SIZE=3 WIDTH=100% ALIGN=Center NOSHADE>
<H4><B><PRE>
<A NAME = "S19OS9"></A><FONT COLOR="#FF0000">S19OS9 CONVERSION UTILITY</FONT>

BACKGROUND 


   OS9  is  an  Operating System for the TRS-80/Tandy Color Com-
puters based on the 6809/6309 processors.  The open source  ver-
sion  of  the  OS9 operating system is NitrOS-9 and is available
at:  

    The NitrOS-9 Project
    http://www.nitros9.org


The s19os9 utility package contains the following:

   1)  OS9  definition files and an  OS9 assembler module
       which creates the OS9 header, code and data areas,
       and the module CRC block:

            os9_mod.def       OS9 Module Definitions
            os9_sys.def       OS9 Sytem  Definitions
            os9_mod.asm       OS9 Module Begin / End Code

   2)  a program, s19os9, to post-process  assembled  OS9
       modules from S19 format into  binary  OS9  modules
       with the appropriate  header  checksum  and module
       CRC values calculated.


   The  file os9_mod.def contains module definitions used in the
header of OS9 binary files and was  derived  from  the  NitrOS-9
file os9_mod.def.  

   The  file  os9_sys.def contains system definitions pertaining
to system service request codes, system reserved calls, I/O ser-
vice  request  calls,  file  access modes, signal codes, get/put
status codes, module offsets, and error codes.   This  file  was
derived from the NitrOS-9 file os9defs.a.  


CREATING AN OS9 MODULE 


   This  section describes how to create an OS9 module using the
files os9_mod.def, os9_sys.def, and os9_mod.asm.  

   When  creating  an OS9 module certain parameters are required
by the os9_mod.asm file to create the appropriate headers.   The
list of supported parameters is listed here:  

   Basic Header:

       .define OS9_ModNam,     "Module_Name"
       .define OS9_Typ,        "Type_Value"
       .define OS9_Lng,        "Language_Value"
       .define OS9_Att,        "Attributes_Value"
       .define OS9_Rev,        "Revision_Value"

   General Parameters:
       .define OS9_ModExe,     "Module Entry Point Offset"
       .define OS9_ModMem,     "Module Permanent Storage"

   Device Driver Parameters:

       .define OS9_Mod,        "Module Mode"

   Descriptor Parameters:

       .define OS9_FMN,        "Device Driver Name Label"
       .define OS9_DDR,        "Device Driver Name Label"
       .define OS9_AbsAdr02,   "Device Absolute Address <23:16>"
       .define OS9_AbsAdr01,   "Device Absolute Address <15:08>"
       .define OS9_AbsAdr00,   "Device Absolute Address <07:00>"
       .define OS9_Opt,        "Descriptor Option"
       .define OS9_DType,      "Descriptor Data Type"


   The  OS9 Module file os9_mod.asm supports the creation of the
following simple module types:  

  SYSTM         -       System Module
  PRGRM         -       Program Module
  SBTRN         -       Subroutine Module
  DRIVR         -       Device Driver Module
  FLMGR         -       File Manager Module
  DEVIC         -       Device Descriptor Module


   The  following code shows the steps required when creating an
OS9 program using the os9_mod.asm file.  os9_mod.asm  loads  the
os9_mod.def  and  os9_sys.def files, defines the software inter-
rupt macro os9, and creates  the  os9  program  header  and  crc
blocks.  


Step 1:  Define Header Values 

        ;****
        ; Step 1:
        ; Use the .define assembler directive
        ; to insert the parameters into the
        ; os9_mod.asm's header structure.
        ;
        ;       Note:   See the file os9_mod.asm for
        ;               parameter names and definitions.
        ;
        .title          List Program

        .sbttl          Header Definitions
        
        .define OS9_ModNam,     "LSTNAM"
        .define OS9_Typ,        "PRGRM"
        .define OS9_Lng,        "OBJCT"
        .define OS9_Att,        "REENT"
        .define OS9_Rev,        "1"
        .define OS9_ModExe,     "LSTENT"
        .define OS9_ModMem,     "LSTMEM"


Step 2:  Create The Module Header 

        ; Step 2:
        ; Set the symbol OS9_Module equal to 1
        ; and .include the file os9_mod.asm.

        OS9_Module = 1          ; OS9 Module Begin (==1)
;       .include        "os9_mod.asm"
        .nlist
        .include        "os9_mod.asm"
        .list



   With  OS9_Module = 1  the following code is inserted into the
code stream:  

        .define os9,    "swi2   .byte"  ; os9 macro

        ; Include OS9 Definition Files
        ; os9_sys.def Listing Disabled

        .nlist
        .include        "os9_sys.def"
        .list
        ; os9_mod.def Listing Disabled
        .nlist
        .include        "os9_mod.def"
        .list

        ; Define The OS9 Module Bank and Areas.
        ;
        ; Place the module program code in area OS9_Module
        ; and the module data in area OS9_Data.
        ;

        .bank   OS9_Module      (BASE=0,FSFX=_OS9)
        .area   OS9_Module      (REL,CON,BANK=OS9_Module)

        .bank   OS9_Data        (BASE=0,FSFX=_DAT)
        .area   OS9_Data        (REL,CON,BANK=OS9_Data)


        .area   OS9_Module

        OS9_ModBgn = .

        .byte   OS9_ID0, OS9_ID1
                        ; OS9 Module Sync Bytes
        .word   OS9_ModEnd - OS9_ModBgn
                        ; Length (Includes 3 CRC Bytes)
        .word   OS9_ModNam - OS9_ModBgn
                        ; Offset to Module Name String
        .byte   OS9_Typ | OS9_Lng
                        ; Type / Language
        .byte   OS9_Att | OS9_Rev
                        ; Attributes / Revision
        .byte   0xFF
                        ; Header Parity
        .word   OS9_ModExe - OS9_ModBgn
                        ; Execution Entry Offset
        .word   OS9_ModMem
                        ; Storage Requirement
        ;       OS9_ModData
                        ; Module Data


Step 3:  Allocate Storage 


   The  next  step  is to add the program data storage space for
the program.  Note that the space is only allocated here and  no
initialization is done.  

        ;*****-----*****-----*****-----*****-----*****-----*****
        ;  LIST UTILITY COMMAND
        ;  Syntax: list &lt;pathname&gt; 
        ;  COPIES INPUT FROM SPECIFIED FILE TO STANDARD OUTPUT

        ; Step 3:
        ; Allocate the storage in .area OS9_Data

        .area   OS9_Data

        ; STATIC STORAGE OFFSETS 
        
        BUFSIZ  .equ    200     ; size of input buffer
        
        Base = .
IPATH = . - Base
        .rmb    1               ; input path number
PRMPTR = . - Base
        .rmb    2               ; parameter pointer
BUFFER = . - Base
        .rmb    BUFSIZ          ; allocate line buffer
        .rmb    200             ; allocate stack
        .rmb    200             ; room for parameter list
LSTMEM = . - Base


C.2.4  Step 4:  Insert The Program Code 


   Once  the data storage space has been allocated then the pro-
gram code is added to .area OS9_Module:  

        ; Step 4:
        ; Insert the Module Code into .area OS9_Module

        .area   OS9_Module

LSTNAM: .strs   "List"          ; String with last byte
                                ; or'd with 0x80
LSTENT: stx     *PRMPTR         ; save parameter ptr
        lda     #READ.          ; select read access mode
        os9     I$OPEN          ; open input file
        bcs     LIST50          ; exit if error
        sta     *IPATH          ; save input path number
        stx     *PRMPTR         ; save updated param ptr

LIST20: lda     *IPATH          ; load input path number
        leax    *BUFFER,U       ; load buffer pointer
        ldy     #BUFSIZ         ; maximum bytes to read
        os9     I$READLN        ; read line of input
        bcs     LIST30          ; exit if error
        lda     #1              ; load std. out. path #
        os9     I$WRITLN        ; output line
        bcc     LIST20          ; Repeat if no error
        bra     LIST50          ; exit if error

LIST30: cmpb    #E$EOF          ; at end of file?
        bne     LIST50          ; branch if not
        lda     *IPATH          ; load input path number
        os9     I$CLOSE         ; close input path
        bcs     LIST50          ; ..exit if error
        ldx     *PRMPTR         ; restore parameter ptr
        lda     ,X
        cmpa    #0x0D           ; End of parameter line?
        bne     LSTENT          ; ..no, list next file
        clrb
LIST50: os9     F$EXIT          ; ... terminate


Step 5:  End Assembly By Inserting CRC 

        ; Step 5:
        ; Set the symbol OS9_Module equal to 0
        ; and .include the file os9_mod.asm.

        OS9_Module = 0          ; OS9 Module End (==0)
;       .include        "os9_mod.asm"
        .nlist
        .include        "os9_mod.asm"
        .list

        .end



   With  OS9_Module = 0  the following code is the last code in-
serted into the code stream:  

        .area   OS9_Module

        ; The 3-Byte Module CRC
        .byte   OS9_CRC0, OS9_CRC1, OS9_CRC2

        OS9_ModEnd = .          ; End of OS9 Module


THE CONVERSION UTILITY:  S19OS9 


   Once you have assembled your module into an .S19 file use the
program s19os9 to create the binary OS9 module file.  

The  program s19os9 is invoked from the command line:

        s19os9 mod.s19 -o mod.bin

   where  mod.s19  is  the input S19 file and mod.bin is the OS9
binary output file.  

   The conversion utility s19os9 reads the .S19 file into an in-
ternal buffer (48K bytes maximum).  As each line  is  read  from
the  .S19  file  the  record length, address, data, and checksum
values are processed checking for invalid characters and a valid
checksum.  

   After  the .S19 file has been loaded into the internal buffer
the OS9 module is checked for correct length, and the OS9 Module
ID,  OS9 Initial Header Checksum, and OS9 Initial Module CRC are
verified.  After these parameters have been checked then the ac-
tual  header  checksum  and module CRC values are calculated and
replace the Initial Module Checksum and CRC values.  The  final-
ized module is then written to the file mod.bin.  

</PRE></B></H4>
<H5><A HREF= #Utilities> =&gt; Section Index</A></H5>

<IMG width=576 height=5 border=0 SRC="rnbow.gif">

<H4>
<P><A HREF="asxxxx.htm#JUMP">
<IMG width=32 height=32 border=0 SRC="spcshp.gif" ALIGN=bottom></A>
<B>...  Exit the ASxxxx Documentation</B></A></P>

<P><A href="../home.htm">
<IMG width=32 height=32 border=0 SRC="home.gif" ALIGN=bottom></A>
<B>...  Home Page</B></P>
</H4>

<H6><P><B>Last Updated: April 2009</B></P></H6>
</BODY> 
</HTML>
